Repository navigation
docs: document the composition catalog and release 2.1.0 - #5
Merged
Merged
Conversation
Adds a repository README and a stack README, and rewrites all nine composition READMEs as consumer-facing contracts. The previous composition READMEs pointed at files that do not exist in this repo (compositions.yaml, examples/, tests/smoke, scripts/verify-composition.sh) and documented no steps, profiles, inputs, or credentials. Each one now covers: - the composition contract (type, schema, job, default profile, runner) - a step x profile matrix, so it is clear which capabilities each lane selects and which steps are dropped from the plan - every schema input with required/optional status and what reads it - deploy and apply gating, plus the credentials each gated path asserts - a component.yaml usage example Repo README covers the trigger -> environment -> profile -> capability pipeline, the CI plan/run matrix, consuming the published package, and the release process. Stack README covers the composition anatomy, the profile lanes, the two layers of deploy gating, and the conventions for adding a composition. Also fixes the terraform composition: the verify profile, described as "full non-mutating verification", included terraform.apply and therefore planned `terraform apply -auto-approve`. Confirmed with a probe component that the Apply step was planned before the change and is not after it. terraform.apply is now declared on the job template alongside the step that uses it, and is selected by no shipped profile. Bumps the stack to 2.1.0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013saWA8jdvjSTjhWGFefzMg
The orun-action defaults to `version: latest`. In May it resolved v1.26.0, matching the provider pinned in kiox.lock, and the publish job passed. It now resolves v2.38.0, and every job fails before running a step with: ✕ remote state auth (oidc exchange): OIDC exchange returned status 403 Same workflow, same secrets, same repo — only the installed CLI changed. Pinning both action invocations to v1.26.0 puts CI back on the version this workspace declares. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013saWA8jdvjSTjhWGFefzMg
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
Documentation for the stack, plus two fixes found while writing and verifying it, plus the version bump to publish it.
New docs
README.md(new)stacks/stack-tectonic-flare/README.md(new)composition.yaml/schema.yaml/jobs/profilesand what each answers), the shared profile lanes, the two layers of deploy gating, the template context, and conventions for adding a compositionRewritten composition READMEs (all 9)
The previous READMEs were scaffolding that described files this repo does not contain —
compositions.yaml(the file iscomposition.yaml),examples/<fixture>,tests/smoke, and./scripts/verify-composition.sh— while documenting no steps, profiles, inputs, or credentials.publish-stackadditionally listedregistryandversionas required inputs; they are optional in the schema and are not read by the job template at all.Each README now documents:
Environment+productionBranchconditions, the three-way branch in the Worker deploy steps, and which credentials are asserted on which pathcomponent.yamlusage exampleFix:
terraformverify profile planned an applyprofiles/terraform-verify.yaml, described as "Full non-mutating verification", listedterraform.applyinincludeCapabilities— so theverifylane plannedterraform apply -auto-approve.Verified with a throwaway
terraformcomponent andorun plan:terraform.applyis removed from theverifyprofile, and is now declared in the job template'scapabilitiesblock alongside the step that already used it (confirmed inert — the profile filter is what selects steps). No shipped profile selects it, which matches the composition's own framing:releaseis "release-grade validation before apply-capable workflows". This is called out in theterraformREADME under a "Changed in 2.1.0" note. No component in this repo uses theterraformcomposition, so nothing here changes behaviour today.Fix: CI was red before this branch, from CLI drift
The first push of this branch failed the
stack-tectonic · dev · Publishcheck before any step ran:sourceplane/orun-actiondefaults toversion: latest. The last green run (16 May) resolved v1.26.0 — the versionkiox.lockpins. Todaylatestresolves v2.38.0, whose remote-state OIDC exchange the backend rejects. Same workflow, same secrets, same repo; only the installed CLI changed.Both action invocations in
.github/workflows/verify.ymlare now pinned tov1.26.0, and CI is green again. This is unrelated to the docs work — it is what unblocks merging.Note the composition's own
setup-orunstep (inside thepublish-stackjob template) still installslatestand resolved v2.38.0 in the green run;orun publishworks fine on it. Only the outer runner needed pinning.Release
stack.yamlmetadata.version→2.1.0(minor: new docs, one profile capability removed from a lane that should never have had it). Merging this publishesghcr.io/sourceplane/saas-stack-tectonic-flare:2.1.0via thestack-tectonic · staging · Publishcheck.Verification
Locally:
In CI (both checks green on
819f39a), the dry-run lane confirms the release target:Every YAML file parses, and all relative links in the new and rewritten markdown resolve to real paths.
Regenerated
.orun/component-tree.yamland.orun/compositions.lock.yamlwere deliberately left out of the commits — the local CLI is a different version from the one that generated them and rewrites unrelated fields.